home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / general / hdf / specs / hdfspecs.lha / HDFSpecs.ch1 < prev    next >
Text File  |  1992-03-04  |  9KB  |  268 lines
  1. 1.1    NCSA HDF Specifications
  2.  
  3. The Basic Structure of HDF Files    1.1
  4.  
  5. National Center for Supercomputing Applications
  6.  
  7. March 1989
  8.  
  9.                                                                 
  10.  
  11.  
  12.  
  13.  
  14. 1.1    NCSA HDF Specifications
  15.  
  16. The Basic Structure of HDF Files    1.1
  17.  
  18. National Center for Supercomputing Applications
  19.  
  20. March 1989
  21.  
  22.                                                                 
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30. Chapter 1    The Basic Structure of HDF Files
  31.  
  32.  
  33.  
  34. Chapter Overview
  35. File Header
  36. Data Object
  37. Data Descriptor
  38. DD Blocks
  39. Data Element
  40. Physical Organization of HDF Files
  41. Sample HDF File
  42.  
  43. Chapter Overview
  44.  
  45. This chapter introduces and describes the components and 
  46. organization of Hierarchical Data Format files.
  47.  
  48.  
  49. File Header
  50.  
  51. The first component of an HDF file is the file header (FH), which 
  52. takes up the first four bytes in an HDF file. The file header is a 
  53. signature that indicates that the file is an HDF file. Specifically, it 
  54. is the 32-bit magic number formed by the four characters ^N, ^C, 
  55. ^S, and ^A (hexadecimal value 0e031301).
  56.  
  57. NOTE:  On some machines the order of bytes in the file header 
  58. might be swapped when the header is written to an HDF file, 
  59. causing these characters to be written in the wrong order. To 
  60. maintain machine portability when developing software for such 
  61. machines, you should counteract this byte-swapping by making 
  62. sure the characters are read and written in the exact order shown.
  63.  
  64.  
  65. Data Object
  66.  
  67. The basic building block in an HDF file is the data object, which 
  68. contains both data and information about the data. A data object 
  69. has two parts:  a 12-byte data descriptor (DD) and a data element. 
  70. Figure 1.1 shows three examples of data objects.
  71.  
  72. As the names imply, the data descriptor gives information about 
  73. the data, and the data element is the data itself. In other words, all 
  74. data in an HDF file has attached to it information about itself. For 
  75. this reason, HDF files are examples of self-describing files.
  76.  
  77. Figure 1.1    Three Data Objects
  78.                                           
  79.  
  80.  
  81.  
  82. Data Descriptor (DD)
  83. A DD has four fields:  a 16-bit tag, a 16-bit reference number, a 
  84. 32-bit data offset, and a 32-bit data length. These parts of a DD are 
  85. depicted in Figure 1.2 and are briefly described in Table 1.1. 
  86. Explanations of each part appear in the paragraphs following 
  87. Table 1.1.
  88.  
  89. Figure 1.2  A Data Descriptor 
  90. (DD)
  91.                                         
  92.  
  93.  
  94.  
  95. Table 1.1    Parts of a Data 
  96. Descriptor
  97. Part    Description
  98. tag    designates the type of data in a data element
  99. reference number    uniquely distinguishes corresponding data 
  100. element from others with the same tag
  101. data identifier    tag/ref; uniquely identifies data element
  102. offset    byte offset of corresponding data element
  103. length    length of data element
  104.  
  105.  
  106. Tag
  107. A tag is the part of a data descriptor that tells what kind of data is 
  108. contained in the corresponding data element. A tag is actually a 
  109. 16-bit unsigned integer between 1 and 65535, but every tag is also 
  110. usually given a name that programs can refer to instead of the 
  111. number. If a DD has no corresponding data element, the value of 
  112. its tag is no data (NULL). A tag may never be zero.
  113.  
  114. The extensibility of HDF results from the fact that new tags can be 
  115. assigned when it becomes necessary to store new types of data 
  116. elements. Tags are assigned by NCSA as part of the specification 
  117. of HDF. Appendix A contains full specifications for all currently 
  118. supported NCSA HDF tags.
  119.  
  120. As NCSA HDF grows, the number of tags will grow. In addition to 
  121. the tags that are defined in this document, some tags are reserved 
  122. for experimentation and some are delegated to other individuals or 
  123. institutions in "round" intervals of 100's, 1000's, or 10,000's. All 
  124. numbers that are not already designated are reserved for future 
  125. definition by NCSA. Appendix A, "NCSA HDF Tags," contains 
  126. the current number assignments.
  127.  
  128.  
  129. Reference Number
  130. For each occurrence of a tag in an HDF file, a unique reference 
  131. number is stored with the tag in the data descriptor. Reference 
  132. numbers are 16-bit unsigned integers.
  133.  
  134. Data Identifier
  135. The combination of a tag and its reference number uniquely 
  136. identifies the corresponding data object in the file. For this reason, 
  137. the tag/ref combination is sometimes referred to as a data 
  138. identifier.
  139.  
  140.  
  141. Data Offset and Length
  142. The data offset reflects the byte position of the corresponding data 
  143. element from the start of the file. The length gives the number of 
  144. bytes occupied by the data element. Offset and length are both 32-bit 
  145. unsigned integers.
  146.  
  147.  
  148. DD Blocks
  149. Data descriptors are stored physically in a linked list of blocks 
  150. called data descriptor blocks, or DD blocks. The individual 
  151. components of a data descriptor block are depicted in Figure 1.3. 
  152. All of the DDs in a DD block are assumed to contain significant 
  153. data unless they have a tag that is equal to NULL (no data).
  154.  
  155. In addition to its DDs, each data descriptor block has a data 
  156. descriptor header (DDH). The DDH has two fields╤a block size 
  157. field and a next block field. The block size field is a 16-bit 
  158. unsigned integer that indicates the number of DDs in the following 
  159. DD block. The next block field is 32-bit unsigned integer giving 
  160. the offset of the next DD block, if there is one. The last DDH in the 
  161. list contains a 0 in its next block field.
  162.  
  163.  
  164. Figure 1.3    Model of a Data Descriptor Block
  165.  
  166.                                                            
  167.  
  168.  
  169.  
  170. Data Element
  171. A data element is the raw data part of a data object. Its basic data 
  172. type is determined by its tag, but other interpretive information 
  173. may be required before it can be processed properly.
  174.  
  175. Each data element is stored as a set of contiguous bytes starting at 
  176. the offset given in the corresponding DD (see Figure 1.4).
  177.  
  178.  
  179. Figure 1.4    Sample Data Descriptor Block
  180.  
  181.                                                            
  182.  
  183.  
  184.  
  185. Physical Organization of HDF Files
  186.  
  187. Physically, the file header, DD blocks, and data elements are 
  188. organized as follows. The file header is followed by the first DD 
  189. block, which is followed by data elements and, if necessary, more 
  190. DD blocks. These relationships are summarized in Table 1.2.
  191.  
  192. There are no rules governing the distribution of DD blocks and 
  193. data elements within a file, except that the first DD block must 
  194. follow immediately after the header. The pointers in the DD 
  195. headers connect the DD blocks in a linked list, and the offsets in 
  196. the individual DDs connect the DDs to the data elements. Beyond 
  197. this basic structure there is no necessary ordering among the 
  198. objects in an HDF file, although there are guidelines that you are 
  199. encouraged to follow. More information regarding these 
  200. guidelines is presented in Chapter 4, "HDF Conventions."
  201.  
  202. Table 1.2    Summary of the 
  203. Relationships 
  204. among Parts of an 
  205. HDF File
  206. Part    Constituents
  207. HDF-file    FH, DD-block, data, DD-block, data, DD-block, data...
  208. FH    ^N ^C ^S ^A [32 bits]
  209. DD-block    DDH, DD, DD, DD...
  210. DDH    number-of-DDs [16 bits], offset-to-next-DD block [32 bits]
  211. DD    tag [16 bits], ref [16 bits], offset [32 bits], length [32 bits]
  212.  
  213.  
  214.  
  215. Sample HDF File
  216.  
  217. Consider an HDF file that contains two 400-by-600 8-bit raster 
  218. images. Typically, such a file might contain the objects described 
  219. in Table 1.3.
  220.  
  221. Table 1.3    Sample Data Objects 
  222. in an HDF File
  223. Tag    Ref    Data
  224. FID    1    file identifier:  user-assigned title for file
  225. FD    1    file descriptor:  user-assigned block of text
  226.         describing overall file contents
  227. IP8    1    image palette (768 bytes)
  228. ID8    1    x and y dimensions of the 2D arrays that contain 
  229.         the raster images (4 bytes)
  230. RI8    1    first 2D array of raster image pixel data (x*y bytes)
  231. RI8    2    second 2D array of pixel data (also x*y bytes)
  232.  
  233.  
  234. Assuming, for example, that the size of a DD block is 10 DDs, the 
  235. physical organization of the contents of the file might be described 
  236. as shown in Figure 1.5.
  237.  
  238. Figure 1.5    Physical 
  239.     Representation of Data 
  240.     Objects
  241.  
  242.  Offset    Contents
  243.     0    FH
  244.     4    DDH    (5    0L)
  245.     10    DD    (FID    1    130    4)
  246.     22    DD    (FD    1    134    41)
  247.     34    DD    (IP8    1    175    768)
  248.     46    DD    (ID8    1    943    4)
  249.     58    DD    (RI8    1    947    240000)
  250.     70    DD    (RI8    2    240947    240000)
  251.     82    DD    (empty)
  252.     94    DD    (empty)
  253.     106    DD    (empty)
  254.     118    DD    (empty)
  255.     130    "sw3"
  256.     134    "solar wind simulation: third try. 8/8/88"
  257.     175    <data for the image palette>
  258.     943    <data for the image dimensions>:  400, 600
  259.     947    <data for the first raster image>
  260.     240947    <data for the second raster image>
  261.  
  262.  
  263. In this instance, the file contains two raster images. The two 
  264. images have the same dimensions and are to be used with the same 
  265. palette. So, the same data objects for the palette (IP8) and 
  266. dimension record (ID8) can be used with both images.
  267.  
  268.